home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 25 / Cream of the Crop 25.iso / utility / ffe101.zip / SOUND.SWG / 0013_IFF EXPLANATION.pas < prev    next >
Pascal/Delphi Source File  |  1996-09-04  |  64KB  |  1,329 lines

  1. "EA IFF 85" Standard for Interchange Format Files
  2.  
  3. Document Date:          January 14, 1985
  4. From:                   Jerry Morrison, Electronic Arts
  5. Status of Standard:     Released and in use
  6.  
  7. 1. Introduction
  8.  
  9. Standards are Good for Software Developers
  10.  
  11. As  home computer hardware evolves to  better and better media machines,
  12. the  demand  increases  for  higher  quality,  more  detailed data. Data
  13. development  gets  more  expensive, requires  more  expertise and better
  14. tools,  and has to be shared  across projects. Think about several ports
  15. of a product on one CD-ROM with 500M Bytes of common data!
  16.  
  17. Development  tools  need  standard  interchange  file  formats.  Imagine
  18. scanning  in  images of "player" shapes,  moving them to a paint program
  19. for  editing,  then incorporating them into  a  game. Or writing a theme
  20. song  with  a Macintosh score editor  and incorporating it into an Amiga
  21. game.  The  data must at times  be transformed, clipped, filled out, and
  22. moved  across machine kinds. Media projects will depend on data transfer
  23. from graphic, music, sound effect, animation, and script tools.
  24.  
  25. Standards are Good for Software Users
  26.  
  27. Customers  should  be able to move  their own data between independently
  28. developed  software  products.  And  they should  be  able  to  buy data
  29. libraries usable across many such products. The types of data objects to
  30. exchange are open-ended and include plain and formatted text, raster and
  31. structured  graphics,  fonts, music,  sound  effects, musical instrument
  32. descriptions, and animation.
  33.  
  34. The  problem with expedient file formats  typically memory dumps is that
  35. they're too provincial. By designing data for one particular use (e.g. a
  36. screen  snapshot), they preclude future expansion (would you like a full
  37. page  picture?  a multi-page document?).  In  neglecting the possibility
  38. that  other programs might read their data, they fail to save contextual
  39. information (how many bit planes? what resolution?). Ignoring that other
  40. programs  might  create  such files,  they're  intolerant  of extra data
  41. (texture  palette for a picture editor), missing data (no color map), or
  42. minor  variations  (smaller image). In  practice, a filed representation
  43. should  rarely mirror an in-memory  representation. The former should be
  44. designed  for  longevity; the latter to  optimize the manipulations of a
  45. particular  program.  The  same filed data  will  be read into different
  46. memory formats by different programs.
  47.  
  48. The IFF philosophy: "A little behind-the-scenes conversion when programs
  49. read  and  write  files  is  far  better  than  NxM  explicit conversion
  50. utilities for highly specialized formats."
  51.  
  52. So  we need some standardization  for data interchange among development
  53. tools  and  products.  The more developers  that  adopt  a standard, the
  54. better for all of us and our customers.
  55.  
  56. Here is "EA IFF 1985"
  57.  
  58. Here is our offering: Electronic Arts' IFF standard for Interchange File
  59. Format.  The full name is "EA IFF 1985". Alternatives and justifications
  60. are  included for certain choices. Public domain subroutine packages and
  61. utility  programs  are  available  to  make  it  easy  to  write and use
  62. IFF-compatible programs.
  63.  
  64. Part  1  introduces the standard. Part  2  presents its requirements and
  65. background.  Parts  3, 4, and 5  define the primitive data types, FORMs,
  66. and  LISTs, respectively, and how to define new high level types. Part 6
  67. specifies the top level file structure. Appendix A is included for quick
  68. reference  and  Appendix  B  names  the  committee  responsible for this
  69. standard.
  70.  
  71. References
  72.  
  73. American  National Standard Additional Control Codes for Use with ASCII,
  74. ANSI  standard  3.64-1979  for  an 8-bit  character  set.  See  also ISO
  75. standard 2022 and ISO/DIS standard 6429.2.
  76.  
  77. Amiga[tm] is a trademark of Commodore-Amiga, Inc.
  78.  
  79. C,  A Reference Manual, Samuel P. Harbison and Guy L. Steele Jr., Tartan
  80. Laboratories. Prentice-Hall, Englewood Cliffs, NJ, 1984.
  81.  
  82. Compiler  Construction, An Advanced Course, edited by F. L. Bauer and J.
  83. Eickel  (Springer-Verlag,  1976). This book is  one  of many sources for
  84. information on recursive descent parsing.
  85.  
  86. DIF  Technical  Specification (c)1981 by  Software Arts, Inc. DIF[tm] is
  87. the  format for spreadsheet data interchange developed by Software Arts,
  88. Inc. DIF[tm] is a trademark of Software Arts, Inc.
  89.  
  90. Electronic Arts[tm] is a trademark of Electronic Arts.
  91.  
  92. "FTXT" IFF Formatted Text, from Electronic Arts. IFF supplement document
  93. for a text format.
  94.  
  95. Inside  Macintosh  (c)  1982, 1983, 1984,  1985  Apple Computer, Inc., a
  96. programmer's   reference  manual.  Apple(R)  is  a  trademark  of  Apple
  97. Computer,  Inc. Macintosh[tm] is a trademark licensed to Apple Computer,
  98. Inc.
  99.  
  100. "ILBM"  IFF  Interleaved  Bitmap, from  Electronic  Arts. IFF supplement
  101. document for a raster image format.
  102.  
  103. M68000  16/32-Bit Microprocessor Programmer's  Reference Manual(c) 1984,
  104. 1982, 1980, 1979 by Motorola, Inc.
  105.  
  106. PostScript   Language  Manual  (c)   1984  Adobe  Systems  Incorporated.
  107. PostScript[tm]   is  a  trademark  of  Adobe  Systems,  Inc.  Times  and
  108. Helvetica(R) are trademarks of Allied Corporation.
  109.  
  110. InterScript:  A Proposal for a Standard  for the Interchange of Editable
  111. Documents  (c)1984  Xerox Corporation.  Introduction  to InterScript (c)
  112. 1985 Xerox Corporation.
  113.  
  114. 2. Background for Designers
  115.  
  116. Part  2  is  about  the  background,  requirements,  and  goals  for the
  117. standard.  It's  geared for people who want  to  design new types of IFF
  118. objects.  People just interested in using  the standard may wish to skip
  119. this part.
  120.  
  121. What Do We Need?
  122.  
  123. A  standard  should  be long on  prescription  and short on overhead. It
  124. should  give  lots  of rules for  designing  programs and data files for
  125. synergy.  But  neither the programs nor  the  files should cost too much
  126. more  than  the expedient variety. While  we're looking to a future with
  127. CD-ROMs  and  perpendicular  recording, the  standard  must work well on
  128. floppy disks.
  129.  
  130. For  program portability, simplicity, and  efficiency, formats should be
  131. designed  with more than one implementation style in mind. (In practice,
  132. pure  stream  I/O is adequate although  random access makes it easier to
  133. write  files.) It ought to be possible to  read one of many objects in a
  134. file without scanning all the preceding data. Some programs need to read
  135. and  play  out  their  data in real  time,  so  we need good compromises
  136. between generality and efficiency.
  137.  
  138. As  much as we need standards, they  can't hold up product schedules. So
  139. we  also  need a kind of  decentralized extensibility where any software
  140. developer can define and refine new object types without some "standards
  141. authority"  in  the  loop. Developers must  be  able  to extend existing
  142. formats  in a forward- and backward-compatible way. A central repository
  143. for  design  information  and  example programs  can  help  us take full
  144. advantage of the standard.
  145.  
  146. For  convenience,  data formats should  heed the restrictions of various
  147. processors  and  environments. E.g.  word-alignment  greatly helps 68000
  148. access at insignificant cost to 8088 programs.
  149.  
  150. Other  goals include the ability to share common elements over a list of
  151. objects  and the ability to construct composite objects containing other
  152. data objects with structural information like directories.
  153.  
  154. And  finally, "Simple things should be  simple and complex things should
  155. be possible." Alan Kay.
  156.  
  157. Think Ahead
  158.  
  159. Let's  think ahead and build programs that read and write files for each
  160. other  and  for programs yet to be  designed. Build data formats to last
  161. for future computers so long as the overhead is acceptable. This extends
  162. the usefulness and life of today's programs and data.
  163.  
  164. To  maximize  interconnectivity,  the standard  file  structure  and the
  165. specific  object formats must all be general and extensible. Think ahead
  166. when  designing an object. It should  serve many purposes and allow many
  167. programs  to  store  and read back  all  the information they need; even
  168. squeeze  in custom data. Then a  programmer can store the available data
  169. and  is  encouraged  to  include  fixed  contextual  details.  Recipient
  170. programs  can  read the needed  parts,  skip unrecognized stuff, default
  171. missing  data, and use the stored context  to help transform the data as
  172. needed.
  173.  
  174. Scope
  175.  
  176. IFF  addresses  these needs by defining  a standard file structure, some
  177. initial  data  object  types, ways to  define  new  types, and rules for
  178. accessing  these  files.  We  can accomplish  a  great  deal  by writing
  179. programs   according   to  this  standard,   but   don't  expect  direct
  180. compatibility  with existing software. We'll need conversion programs to
  181. bridge the gap from the old world.
  182.  
  183. IFF  is  geared for computers that  readily process information in 8-bit
  184. bytes.  It  assumes a "physical layer"  of data storage and transmission
  185. that  reliably maintains "files" as strings of 8-bit bytes. The standard
  186. treats  a "file" as a container of  data bytes and is independent of how
  187. to find a file and whether it has a byte count.
  188.  
  189. This  standard does not by itself  implement a clipboard for cutting and
  190. pasting  data  between programs. A  clipboard  needs software to mediate
  191. access,  to maintain a "contents version  number" so programs can detect
  192. updates, and to manage the data in "virtual memory".
  193.  
  194. Data Abstraction
  195.  
  196. The  basic  problem  is  how to  represent  information  in a way that's
  197. program-independent,  compiler-  independent,  machine-independent,  and
  198. device-independent.
  199.  
  200. The  computer  science  approach is  "data  abstraction",  also known as
  201. "objects", "actors", and "abstract data types". A data abstraction has a
  202. "concrete   representation"   (its   storage   format),   an   "abstract
  203. representation"  (its capabilities and uses), and access procedures that
  204. isolate  all the calling software from the concrete representation. Only
  205. the  access  procedures touch the  data  storage. Hiding mutable details
  206. behind   an   interface  is  called   "information  hiding".  What  data
  207. abstraction  does  is abstract from  details of implementing the object,
  208. namely   the   selected  storage   representation   and  algorithms  for
  209. manipulating it.
  210.  
  211. The  power  of  this  approach is  modularity.  By  adjusting the access
  212. procedures  we can extend and restructure the data without impacting the
  213. interface  or its callers. Conversely, we can extend and restructure the
  214. interface  and callers without making existing data obsolete. It's great
  215. for interchange!
  216.  
  217. But we seem to need the opposite: fixed file formats for all programs to
  218. access.  Actually, we could file  data abstractions ("filed objects") by
  219. storing the data and access procedures together. We'd have to encode the
  220. access procedures in a standard machine-independent programming language
  221. la  PostScript.  Even still, the interface  can't evolve freely since we
  222. can't  update  all  copies of the  access  procedures.  So we'll have to
  223. design our abstract representations for limited evolution and occasional
  224. revolution (conversion).
  225.  
  226. In  any  case,  today's  microcomputers  can't  practically  store  data
  227. abstractions.  They can do the next best thing: store arbitrary types of
  228. data  in "data chunks", each with a  type identifier and a length count.
  229. The type identifier is a reference by name to the access procedures (any
  230. local  implementation).  The length  count  enables storage-level object
  231. operations like "copy" and "skip to next" independent of object type.
  232.  
  233. Chunk  writing  is  straightforward. Chunk  reading  requires  a trivial
  234. parser  to scan each chunk and  dispatch to the proper access/conversion
  235. procedure. Reading chunks nested inside other chunks requires recursion,
  236. but no lookahead or backup.
  237.  
  238. That's the main idea of IFF. There are, of course, a few other detailsI
  239.  
  240. Previous Work
  241.  
  242. Where our needs are similar, we borrow from existing standards.
  243.  
  244. Our  basic need to move data between independently developed programs is
  245. similar  to  that  addressed  by  the  Apple  Macintosh  desk  scrap  or
  246. "clipboard"  [Inside  Macintosh  chapter  "Scrap  Manager"].  The  Scrap
  247. Manager  works  closely  with the Resource  Manager,  a  handy filer and
  248. swapper  for  data  objects  (text  strings,  dialog  window  templates,
  249. pictures,  fontsI) including types yet  to be designed [Inside Macintosh
  250. chapter   "Resource  Manager"].  The  Resource   Manager  is  a  kin  to
  251. Smalltalk's object swapper.
  252.  
  253. We  will  probably  write a Macintosh  desk  accessory that converts IFF
  254. files to and from the Macintosh clipboard for quick and easy interchange
  255. with programs like MacPaint and Resource Mover.
  256.  
  257. Macintosh  uses a simple and elegant scheme of 4-character "identifiers"
  258. to identify resource types, clipboard format types, file types, and file
  259. creator  programs.  Alternatives  are unique  ID  numbers  assigned by a
  260. central  authority  or  by hierarchical  authorities,  unique ID numbers
  261. generated  by  algorithm,  other  fixed  length  character  strings, and
  262. variable length strings. Character string identifiers double as readable
  263. signposts  in  data files and programs. The  choice of 4 characters is a
  264. good  tradeoff between storage space, fetch/compare/store time, and name
  265. space size. We'll honor Apple's designers by adopting this scheme.
  266.  
  267. "PICT"  is  a  good  example of  a  standard  structured graphics format
  268. (including  raster  images) and its  many uses [Inside Macintosh chapter
  269. "QuickDraw"].  Macintosh  provides QuickDraw routines  in ROM to create,
  270. manipulate,  and  display  PICTs. Any application  can  create a PICT by
  271. simply  asking QuickDraw to record a sequence of drawing commands. Since
  272. it's  just  as easy to ask QuickDraw to  render  a PICT to a screen or a
  273. printer,  it's very effective to pass them between programs, say from an
  274. illustrator  to a word processor. An important feature is the ability to
  275. store  "comments"  in a PICT which  QuickDraw  will ignore. Actually, it
  276. passes them to your optional custom "comment handler".
  277.  
  278. PostScript,  Adobe's  print  file  standard, is  a  more  general way to
  279. represent any print image (which is a specification for putting marks on
  280. paper)   [PostScript   Language  Manual].  In   fact,  PostScript  is  a
  281. full-fledged  programming language. To interpret a PostScript program is
  282. to  render a document on a raster output device. The language is defined
  283. in  layers: a lexical layer of  identifiers, constants, and operators; a
  284. layer  of  reverse polish semantics including  scope  rules and a way to
  285. define  new  subroutines;  and  a  printing-specific  layer  of built-in
  286. identifiers  and operators for rendering graphic images. It is clearly a
  287. powerful  (Turing  equivalent)  image definition  language.  PICT  and a
  288. subset of PostScript are candidates for structured graphics standards.
  289.  
  290. A  PostScript  document  can  be printed  on  any  raster  output device
  291. (including a display) but cannot generally be edited. That's because the
  292. original  flexibility  and constraints have  been  discarded. Besides, a
  293. PostScript  program  may use arbitrary  computation to supply parameters
  294. like  placement  and  size  to  each  operator.  A  QuickDraw  PICT,  in
  295. comparison,   is   a  more  restricted   format  of  graphic  primitives
  296. parameterized  by constants. So a PICT can be edited at the level of the
  297. primitives,  e.g.  move  or thicken a line.  It  cannot be edited at the
  298. higher level of, say, the bar chart data which generated the picture.
  299.  
  300. PostScript has another limitation: Not all kinds of data amount to marks
  301. on paper. A musical instrument description is one example. PostScript is
  302. just not geared for such uses.
  303.  
  304. "DIF" is another example of data being stored in a general format usable
  305. by  future  programs [DIF Technical Specification].  DIF is a format for
  306. spreadsheet  data interchange. DIF and  PostScript are both expressed in
  307. plain  ASCII  text  files. This is  very  handy for printing, debugging,
  308. experimenting,  and transmitting across modems.  It can have substantial
  309. cost in compaction and read/write work, depending on use. We won't store
  310. IFF files this way but we could define an ASCII alternate representation
  311. with a converter program.
  312.  
  313. InterScript  is  Xerox' standard for  interchange  of editable documents
  314. [Introduction  to  InterScript]. It approaches  a harder problem: How to
  315. represent  editable word processor documents  that may contain formatted
  316. text,  pictures,  cross-references like figure  numbers, and even highly
  317. specialized  objects  like mathematical  equations?  InterScript aims to
  318. define  one  standard representation for  each kind of information. Each
  319. InterScript-compatible  editor  is supposed to  preserve  the objects it
  320. doesn't  understand  and  even maintain  nested  cross-references.  So a
  321. simple  word  processor would let you edit  the text of a fancy document
  322. without discarding the equations or disrupting the equation numbers.
  323.  
  324. Our  task  is similarly to store  high level information and preserve as
  325. much  content as practical while moving it between programs. But we need
  326. to  span a larger universe of data  types and cannot expect to centrally
  327. define  them  all. Fortunately, we don't  need to make programs preserve
  328. information  that  they  don't understand. And  for  better or worse, we
  329. don't have to tackle general-purpose cross-references yet.
  330.  
  331.  
  332. 3. Primitive Data Types
  333.  
  334. Atomic components such as integers and characters that are interpretable
  335. directly  by the CPU are specified in  one format for all processors. We
  336. chose a format that's most convenient for the Motorola MC68000 processor
  337. [M68000 16/32-Bit Microprocessor Programmer's Reference Manual].
  338.  
  339. N.B.:  Part  3 dictates the format  for "primitive" data types where and
  340. only  where  used  in the overall  file  structure and standard kinds of
  341. chunks (Cf. Chunks). The number of such occurrences will be small enough
  342. that  the  costs  of conversion,  storage,  and management of processor-
  343. specific  files  would far exceed the  costs of conversion during I/O by
  344. "foreign"  programs.  A  particular data chunk  may  be specified with a
  345. different  format for its internal primitive types or with processor- or
  346. environment-  speci  fic variants if  necessary to optimize local usage.
  347. Since  that hurts data interchange, it's not recommended. (Cf. Designing
  348. New Data Sections, in Part 4.)
  349.  
  350. Alignment
  351.  
  352. All  data objects larger than a byte  are aligned on even byte addresses
  353. relative  to the start of the file.  This may require padding. Pad bytes
  354. are to be written as zeros, but don't count on that when reading.
  355.  
  356. This  means that every odd-length "chunk"  (see below) must be padded so
  357. that  the  next  one will fall on  an  even boundary. Also, designers of
  358. structures to be stored in chunks should include pad fields where needed
  359. to  align every field larger than a  byte. Zeros should be stored in all
  360. the pad bytes.
  361.  
  362. Justification:  Even-alignment causes a little extra work for files that
  363. are  used  only  on  certain processors  but  allows  68000  programs to
  364. construct  and scan the data in memory and do block I/O. You just add an
  365. occasional  pad  field  to data structures  that  you're  going to block
  366. read/write  or else stream read/write an extra byte. And the same source
  367. code  works on all processors. Unspecified alignment, on the other hand,
  368. would  force 68000 programs to (dis)assemble word and long-word data one
  369. byte  at a time. Pretty cumbersome in  a high level language. And if you
  370. don't  conditionally  compile that out  for  other processors, you won't
  371. gain anything.
  372.  
  373. Numbers
  374.  
  375. Numeric  types  supported  are two's  complement  binary integers in the
  376. format  used  by the MC68000 processor  high byte first, high word first
  377. the  reverse  of  8088 and 6502  format.  They could potentially include
  378. signed  and  unsigned 8, 16, and 32  bit  integers but the standard only
  379. uses the following:
  380.  
  381. UBYTE 8 bits
  382. unsigned WORD 16 bits
  383. signed UWORD 16 bits
  384. unsigned LONG 32 bits signed
  385.  
  386. The  actual type definitions depend on the CPU and the compiler. In this
  387. document,  we'll  express  data type  definitions  in  the C programming
  388. language. [See C, A Reference Manual.] In 68000 Lattice C:
  389.  
  390. typedef unsigned char   UBYTE;  /*  8 bits unsigned     */
  391. typedef short   WORD;   /* 16 bits signed       */
  392. typedef unsigned short  UWORD;  /* 16 bits unsigned     */
  393. typedef long    LONG;   /* 32 bits signed       */
  394.  
  395. Characters
  396.  
  397. The  following  character set is  assumed  wherever characters are used,
  398. e.g. in text strings, IDs, and TEXT chunks (see below).
  399.  
  400. Characters  are encoded in 8-bit ASCII. Characters in the range NUL (hex
  401. 0)  through  DEL (hex 7F) are well  defined by the 7-bit ASCII standard.
  402. IFF uses the graphic group RJS (SP, hex 20) through R~S (hex 7E).
  403.  
  404. Most  of  the  control  character group hex  01  through  hex 1F have no
  405. standard meaning in IFF. The control character LF (hex 0A) is defined as
  406. a  "newline" character. It denotes an intentional line break, that is, a
  407. paragraph  or  line terminator. (There is  no  way to store an automatic
  408. line  break.  That  is  strictly  a  function  of  the  margins  in  the
  409. environment the text is placed.) The control character ESC (hex 1B) is a
  410. reserved  escape  character under the  rules  of ANSI standard 3.64-1979
  411. American  National Standard Additional Control Codes for Use with ASCII,
  412. ISO standard 2022, and ISO/DIS standard 6429.2.
  413.  
  414. Characters  in the range hex 7F through  hex FF are not globally defined
  415. in IFF. They are best left reserved for future standardization. But note
  416. that  the  FORM type FTXT (formatted  text) defines the meaning of these
  417. characters  within  FTXT forms. In  particular,  character values hex 7F
  418. through  hex 9F are control codes while characters hex A0 through hex FF
  419. are extended graphic characters like , as per the ISO and ANSI standards
  420. cited above. [See the supplementary document "FTXT" IFF Formatted Text.]
  421.  
  422. Dates
  423.  
  424. A "creation date" is defined as the date and time a stream of data bytes
  425. was  created.  (Some systems call this  a "last modified date".) Editing
  426. some  data changes its creation date. Moving the data between volumes or
  427. machines does not.
  428.  
  429. The  IFF  standard  date  format will be  one  of  those used in MS-DOS,
  430. Macintosh,  or  Amiga DOS (probably a  32-bit unsigned number of seconds
  431. since a reference point). Issue: Investigate these three.
  432.  
  433. Type IDs
  434.  
  435. A  "type ID", "property name", "FORM  type", or any other IFF identifier
  436. is  a  32-bit value: the concatenation  of  four ASCII characters in the
  437. range  R S (SP, hex 20) through R~S (hex 7E). Spaces (hex 20) should not
  438. precede  printing characters; trailing spaces are ok. Control characters
  439. are forbidden.
  440.  
  441. typedef CHAR ID[4];
  442.  
  443. IDs are compared using a simple 32-bit case-dependent equality test.
  444.  
  445. Data  section  type  IDs (aka FORM  types)  are restriced IDs. (Cf. Data
  446. Sections.)  Since they may be stored  in filename extensions (Cf. Single
  447. Purpose  Files) lower case letters  and punctuation marks are forbidden.
  448. Trailing spaces are ok.
  449.  
  450. Carefully choose those four characters when you pick a new ID. Make them
  451. mnemonic  so  programmers  can look at  an  interchange  format file and
  452. figure  out  what  kind  of data it  contains.  The  name space makes it
  453. possible for developers scattered around the globe to generate ID values
  454. with  minimal  collisions  so long as  they  choose  specific names like
  455. "MUS4"  instead  of  general  ones  like  "TYPE"  and  "FILE".  EA  will
  456. "register" new FORM type IDs and format descriptions as they're devised,
  457. but  collisions will be improbable so there  will be no pressure on this
  458. "clearinghouse" process. Appendix A has a list of currently defined IDs.
  459.  
  460. Sometimes  it's  necessary  to  make  data  format  changes  that aren't
  461. backward  compatible. Since IDs are used  to denote data formats in IFF,
  462. new  IDs are chosen to denote revised formats. Since programs won't read
  463. chunks  whose IDs they don't recognize  (see Chunks, below), the new IDs
  464. keep  old programs from stumbling over new data. The conventional way to
  465. chose a "revision" ID is to increment the last character if it's a digit
  466. or  else  change  the last character to  a  digit. E.g. first and second
  467. revisions  of the ID "XY" would be  "XY1" and "XY2". Revisions of "CMAP"
  468. would be "CMA1" and "CMA2".
  469.  
  470. Chunks
  471.  
  472. Chunks  are the building blocks in the IFF structure. The form expressed
  473. as a C typedef is:
  474.  
  475. typedef struct {
  476.         ID      ckID;
  477.         LONG    ckSize; /* sizeof(ckData) */
  478.         UBYTE   ckData[/* ckSize */];
  479.         } Chunk;
  480.  
  481. We  can diagram an example chunk a "CMAP" chunk containing 12 data bytes
  482. like this:
  483.                         ----------------
  484.                 ckID:   |    'CMAP'    |
  485.                 ckSize: |      12      |
  486.                 ckData: | 0, 0, 0, 32  |   --------
  487.                         | 0, 0, 64, 0  |    12 bytes
  488.                         | 0, 0, 64, 0  |   ---------
  489.                         ----------------
  490.  
  491. The  fixed header part means "Here's a type ckID chunk with ckSize bytes
  492. of data."
  493.  
  494. The  ckID  identifies the format and purpose  of the chunk. As a rule, a
  495. program must recognize ckID to interpret ckData. It should skip over all
  496. unrecognized  chunks. The ckID also serves as a format version number as
  497. long as we pick new IDs to identify new formats of ckData (see above).
  498.  
  499. The  following  ckIDs are universally  reserved  to identify chunks with
  500. particular  IFF  meanings: "LIST", "FORM", "PROP",  "CAT ", and " ". The
  501. special ID " " (4 spaces) is a ckID for "filler" chunks, that is, chunks
  502. that  fill space but have no meaningful contents. The IDs "LIS1" through
  503. "LIS9",  "FOR1"  through "FOR9", and  "CAT1" through "CAT9" are reserved
  504. for future "version number" variations. All IFF-compatible software must
  505. account for these 23 chunk IDs. Appendix A has a list of predefined IDs.
  506.  
  507. The ckSize is a logical block size how many data bytes are in ckData. If
  508. ckData is an odd number of bytes long, a 0 pad byte follows which is not
  509. included  in  ckSize. (Cf. Alignment.) A  chunk's total physical size is
  510. ckSize  rounded up to an even number plus the size of the header. So the
  511. smallest  chunk  is  8  bytes  long with  ckSize  =  0.  For the sake of
  512. following  chunks,  programs  must  respect  every  chunk's  ckSize as a
  513. virtual  end-of-file  for  reading  its  ckData  even  if  that  data is
  514. malformed, e.g. if nested contents are truncated.
  515.  
  516. We  can describe the syntax of a  chunk as a regular expression with "#"
  517. representing  the  ckSize,  i.e. the  length  of  the following {braced}
  518. bytes.  The  "[0]" represents a sometimes  needed pad byte. (The regular
  519. expressions  in this document are collected  in Appendix A along with an
  520. explanation of notation.)
  521.  
  522. Chunk   ::= ID #{ UBYTE* } [0]
  523.  
  524. One  chunk  output technique is to  stream  write a chunk header, stream
  525. write  the chunk contents, then random access back to the header to fill
  526. in  the  size. Another technique is to  make a preliminary pass over the
  527. data to compute the size, then write it out all at once.
  528.  
  529. Strings, String Chunks, and String Properties
  530.  
  531. In  a string of ASCII text, LF denotes a forced line break (paragraph or
  532. line   terminator).   Other  control  characters   are  not  used.  (Cf.
  533. Characters.)
  534.  
  535. The  ckID for a chunk that contains  a string of plain, unformatted text
  536. is  "TEXT". As a practical matter, a  text string should probably not be
  537. longer than 32767 bytes. The standard allows up to 231 - 1 bytes.
  538.  
  539. When  used as a data property (see below),  a text string chunk may be 0
  540. to 255 characters long. Such a string is readily converted to a C string
  541. or  a  Pascal STRING[255]. The ckID of  a  property must be the property
  542. name, not "TEXT".
  543.  
  544. When  used  as a part of a  chunk  or data property, restricted C string
  545. format  is  normally used. That means 0  to 255 characters followed by a
  546. NUL byte (ASCII value 0).
  547.  
  548. Data Properties
  549.  
  550. Data  properties specify attributes for following (non-property) chunks.
  551. A data property essentially says "identifier = value", for example "XY =
  552. (10,  200)",  telling something about  following  chunks. Properties may
  553. only  appear inside data sections ("FORM" chunks, cf. Data Sections) and
  554. property sections ("PROP" chunks, cf. Group PROP).
  555.  
  556. The  form  of a data property is a  special case of Chunk. The ckID is a
  557. property  name  as well as a property  type.  The ckSize should be small
  558. since data properties are intended to be accumulated in RAM when reading
  559. a file. (256 bytes is a reasonable upper bound.) Syntactically:
  560.  
  561. Property::= Chunk
  562.  
  563. When  designing  a  data  object,  use  properties  to  describe context
  564. information  like the size of an image,  even if they don't vary in your
  565. program. Other programs will need this information.
  566.  
  567. Think  of property settings as assignments to variables in a programming
  568. language.  Multiple  assignments  are  redundant  and  local assignments
  569. temporarily  override  global  assignments.  The  order  of  assignments
  570. doesn't  matter as long as they precede the affected chunks. (Cf. LISTs,
  571. CATs, and Shared Properties.)
  572.  
  573. Each  object  type (FORM type) is a  local  name space for property IDs.
  574. Think  of  a  "CMAP"  property  in a  "FORM  ILBM"  as  the qualified ID
  575. "ILBM.CMAP". Property IDs specified when an object type is designed (and
  576. therefore  known to all clients) are called "standard" while specialized
  577. ones added later are "nonstandard".
  578.  
  579. Links
  580.  
  581. Issue:  A  standard mechanism for "links"  or "cross references" is very
  582. desirable  for things like combining  images and sounds into animations.
  583. Perhaps  we'll  define  "link" chunks within  FORMs  that refer to other
  584. FORMs  or to specific chunks within the same and other FORMs. This needs
  585. further work. EA IFF 1985 has no standard link mechanism.
  586.  
  587. For now, it may suffice to read a list of, say, musical instruments, and
  588. then just refer to them within a musical score by index number.
  589.  
  590. File References
  591.  
  592. Issue:  We  may  need a standard form  for  references to other files. A
  593. "file  ref"  could  name  a directory and  a  file  in  the same type of
  594. operating  system as the ref's originator. Following the reference would
  595. expect  the file to be on some mounted volume. In a network environment,
  596. a file ref could name a server, too.
  597.  
  598. Issue: How can we express operating-system independent file refs?
  599.  
  600. Issue:  What about a means to reference a portion of another file? Would
  601. this  be  a  "file ref" plus a  reference  to a "link" within the target
  602. file?
  603.  
  604. 4. Data Sections
  605.  
  606. The  first thing we need of a file is to check: Does it contain IFF data
  607. and,  if  so, does it contain the kind  of data we're looking for? So we
  608. come to the notion of a "data section".
  609.  
  610. A  "data section" or IFF "FORM" is one self-contained "data object" that
  611. might  be  stored in a file by itself.  It is one high level data object
  612. such  as a picture or a sound  effect. The IFF structure "FORM" makes it
  613. self-  identifying. It could be a  composite object like a musical score
  614. with nested musical instrument descriptions.
  615.  
  616. Group FORM
  617.  
  618. A data section is a chunk with ckID "FORM" and this arrangement:
  619.  
  620. FORM  ::=  "FORM"  #{  FormType  (LocalChunk |  FORM  |  LIST  | CAT)* }
  621. FormType::= ID LocalChunk ::= Property | Chunk
  622.  
  623. The  ID  "FORM"  is a syntactic keyword  like  "struct" in C. Think of a
  624. "struct  ILBM" containing a field "CMAP".  If you see "FORM" you'll know
  625. to  expect  a FORM type ID (the  structure name, "ILBM" in this example)
  626. and  a particular contents arrangement or "syntax" (local chunks, FORMs,
  627. LISTs,  and  CATs). (LISTs and CATs are  discussed  in part 5, below.) A
  628. "FORM  ILBM",  in  particular, might contain  a  local  chunk "CMAP", an
  629. "ILBM.CMAP" (to use a qualified name).
  630.  
  631. So  the  chunk ID "FORM" indicates a  data  section. It implies that the
  632. chunk  contains  an  ID and some number  of  nested chunks. In reading a
  633. FORM,  like  any  other  chunk, programs  must  respect  its ckSize as a
  634. virtual end-of-file for reading its contents, even if they're truncated.
  635.  
  636. The  FormType  (or  FORM type) is a  restricted  ID that may not contain
  637. lower  case letters or punctuation characters. (Cf. Type IDs. Cf. Single
  638. Purpose Files.)
  639.  
  640. The  type-specific  information  in  a FORM  is  composed  of its "local
  641. chunks":  data  properties and other chunks.  Each  FORM type is a local
  642. name  space  for local chunk IDs. So  "CMAP"  local chunks in other FORM
  643. types  may  be unrelated to "ILBM.CMAP".  More than that, each FORM type
  644. defines  semantic  scope. If you know what  a  FORM ILBM is, you'll know
  645. what an ILBM.CMAP is.
  646.  
  647. Local chunks defined when the FORM type is designed (and therefore known
  648. to  all  clients of this type)  are  called "standard" while specialized
  649. ones added later are "nonstandard".
  650.  
  651. Among  the  local  chunks,  property  chunks  give  settings for various
  652. details  like  text  font while the  other  chunks  supply the essential
  653. information.  This  distinction  is not  clear  cut.  A property setting
  654. cancelled  by  a later setting of the  same  property has effect only on
  655. data chunks in between. E.g. in the sequence:
  656.  
  657. prop1 = x  (propN = value)*  prop1 = y
  658.  
  659. where the propNs are not prop1, the setting prop1 = x has no effect.
  660.  
  661. The  following universal chunk IDs are reserved inside any FORM: "LIST",
  662. "FORM",  "PROP",  "CAT ", "JJJJ",  "LIS1" through "LIS9", "FOR1" through
  663. "FOR9",  and  "CAT1"  through "CAT9". (Cf.  Chunks.  Cf. Group LIST. Cf.
  664. Group  PROP.)  For clarity, these universal  chunk names may not be FORM
  665. type IDs, either.
  666.  
  667. Part  5, below, talks about grouping FORMs into LISTs and CATs. They let
  668. you  group  a bunch of FORMs but  don't impose any particular meaning or
  669. constraints on the grouping. Read on.
  670.  
  671. Composite FORMs
  672.  
  673. A  FORM  chunk inside a FORM is  a full-fledged data section. This means
  674. you  can build a composite object  like a multi-frame animation sequence
  675. from  available  picture  FORMs and sound  effect  FORMs. You can insert
  676. additional chunks with information like frame rate and frame count.
  677.  
  678. Using composite FORMs, you leverage on existing programs that create and
  679. edit  the  component  FORMs.  Those  editors  may  even  look  into your
  680. composite  object  to copy out its  type of component, although it'll be
  681. the  rare  program that's fancy enough to  do that. Such editors are not
  682. allowed to replace their component objects within your composite object.
  683. That's   because   the  IFF  standard   lets   you  specify  consistency
  684. requirements  for  the composite FORM such  as  maintaining a count or a
  685. directory  of  the components. Only programs  that are written to uphold
  686. the rules of your FORM type should create or modify such FORMs.
  687.  
  688. Therefore,  in  designing a program  that creates composite objects, you
  689. are  strongly  requested to provide a  facility for your users to import
  690. and  export  the  nested FORMs. Import  and  export  could move the data
  691. through a clipboard or a file.
  692.  
  693. Here are several existing FORM types and rules for defining new ones.
  694.  
  695. FTXT
  696.  
  697. An FTXT data section contains text with character formatting information
  698. like  fonts  and  faces.  It has  no  paragraph  or  document formatting
  699. information  like margins and page headers. FORM FTXT is well matched to
  700. the  text  representation  in  Amiga's  Intuition  environment.  See the
  701. supplemental document "FTXT" IFF Formatted Text.
  702.  
  703. ILBM
  704.  
  705. "ILBM"   is   an   InterLeaved   BitMap   image   with   color   map;  a
  706. machine-independent  format for raster images. FORM ILBM is the standard
  707. image  file  format  for the Commodore-Amiga  computer  and is useful in
  708. other  environments,  too.  See  the  supplemental  document  "ILBM" IFF
  709. Interleaved Bitmap.
  710.  
  711. PICS
  712.  
  713. The  data  chunk inside a "PICS" data  section has ID "PICT" and holds a
  714. QuickDraw picture. Issue: Allow more than one PICT in a PICS? See Inside
  715. Macintosh chapter "QuickDraw" for details on PICTs and how to create and
  716. display them on the Macintosh computer.
  717.  
  718. The  only standard property for PICS  is "XY", an optional property that
  719. indicates  the  position of the PICT  relative to "the big picture". The
  720. contents of an XY is a QuickDraw Point.
  721.  
  722. Note:  PICT  may be limited to Macintosh  use, in which case there'll be
  723. another format for structured graphics in other environments.
  724.  
  725. Other Macintosh Resource Types
  726.  
  727. Some  other Macintosh resource types could be adopted for use within IFF
  728. files; perhaps MWRT, ICN, ICN#, and STR#.
  729.  
  730. Issue: Consider the candidates and reserve some more IDs.
  731.  
  732. Designing New Data Sections
  733.  
  734. Supplemental documents will define additional object types. A supplement
  735. needs  to  specify the object's purpose, its  FORM  type ID, the IDs and
  736. formats   of  standard  local  chunks,  and  rules  for  generating  and
  737. interpreting  the  data.  It's  a good  idea  to  supply typedefs and an
  738. example  source  program  that accesses the  new  object. See "ILBM" IFF
  739. Interleaved Bitmap for a good example.
  740.  
  741. Anyone can pick a new FORM type ID but should reserve it with Electronic
  742. Arts at their earliest convenience. [Issue: EA contact person? Hand this
  743. off to another organization?] While decentralized format definitions and
  744. extensions  are  possible  in  IFF,  our  preference  is  to  get design
  745. consensus  by  committee,  implement  a program  to  read  and write it,
  746. perhaps  tune the format, and then publish the format with example code.
  747. Some  organization  should remain in  charge  of answering questions and
  748. coordinating extensions to the format.
  749.  
  750. If  it becomes necessary to revise the  design of some data section, its
  751. FORM  type  ID  will serve as a  version  number  (Cf. Type IDs). E.g. a
  752. revised  "VDEO"  data section could be called  "VDE1". But try to get by
  753. with compatible revisions within the existing FORM type.
  754.  
  755. In   a   new  FORM  type,  the   rules  for  primitive  data  types  and
  756. word-alignment  (Cf.  Primitive  Data Types)  may  be  overriden for the
  757. contents  of its local chunks but not  for the chunk structure itself if
  758. your  documentation spells out the  deviations. If machine-specific type
  759. variants  are needed, e.g. to store  vast numbers of integers in reverse
  760. bit  order,  then  outline  the  conversion  algorithm  and indicate the
  761. variant  inside each file, perhaps via different FORM types. Needless to
  762. say, variations should be minimized.
  763.  
  764. In  designing a FORM type, encapsulate  all the data that other programs
  765. will  need to interpret your files.  E.g. a raster graphics image should
  766. specify the image size even if your program always uses 320 x 200 pixels
  767. x  3 bitplanes. Receiving programs are  then empowered to append or clip
  768. the  image rectangle, to add or drop  bitplanes, etc. This enables a lot
  769. more compatibility.
  770.  
  771. Separate  the  central data (like  musical  notes) from more specialized
  772. information  (like  note  beams)  so  simpler  programs  can extract the
  773. central parts during read-in. Leave room for expansion so other programs
  774. can  squeeze in new kinds of  information (like lyrics). And remember to
  775. keep the property chunks manageably short let's say 2 256 bytes.
  776.  
  777. When  designing  a data object, try to  strike a good tradeoff between a
  778. super-general format and a highly-specialized one. Fit the details to at
  779. least  one  particular  need, for example  a  raster image might as well
  780. store  pixels  in the current machine's scan  order. But add the kind of
  781. generality  that makes it usable with foreseeable hardware and software.
  782. E.g.  use a whole byte for each red, green, and blue color value even if
  783. this  year's  computer has only 4-bit  video  DACs. Think ahead and help
  784. other  programs so long as the overhead is acceptable. E.g. run compress
  785. a  raster by scan line rather than as a unit so future programs can swap
  786. images by scan line to and from secondary storage.
  787.  
  788. Try  to  design  a general purpose  "least  common multiple" format that
  789. encompasses  the needs of many programs without getting too complicated.
  790. Let's  coalesce  our uses around a  few such formats widely separated in
  791. the  vast design space. Two factors make this flexibility and simplicity
  792. practical.  First,  file  storage space  is  getting  very plentiful, so
  793. compaction  is not a priority. Second, nearly any locally-performed data
  794. conversion  work during file reading and  writing will be cheap compared
  795. to the I/O time.
  796.  
  797. It  must be ok to copy a LIST or FORM or CAT intact, e.g. to incorporate
  798. it  into  a composite FORM. So any  kind of internal references within a
  799. FORM must be relative references. They could be relative to the start of
  800. the  containing FORM, relative from the referencing chunk, or a sequence
  801. number into a collection.
  802.  
  803. With  composite FORMs, you leverage on existing programs that create and
  804. edit  the  components.  If you write  a  program  that creates composite
  805. objects,  please provide a facility for  your users to import and export
  806. the  nested FORMs. The import and export functions may move data through
  807. a separate file or a clipboard.
  808.  
  809. Finally, don't forget to specify all implied rules in detail.
  810.  
  811.  
  812. 5. LISTs, CATs, and Shared Properties
  813.  
  814. Data  often needs to be grouped together like a list of icons. Sometimes
  815. a  trick  like  arranging  little images  into  a  big raster works, but
  816. generally  they'll  need  to be structured  as  a first class group. The
  817. objects "LIST" and "CAT" are IFF-universal mechanisms for this purpose.
  818.  
  819. Property  settings  sometimes need to be  shared  over a list of similar
  820. objects.  E.g. a list of icons may  share one color map. LIST provides a
  821. means  called "PROP" to do this. One purpose  of a LIST is to define the
  822. scope  of a PROP. A "CAT", on  the other hand, is simply a concatenation
  823. of objects.
  824.  
  825. Simpler  programs  may skip LISTs and  PROPs  altogether and just handle
  826. FORMs and CATs. All "fully-conforming" IFF programs also know about "CAT
  827. ",  "LIST", and "PROP". Any program that reads a FORM inside a LIST must
  828. process shared PROPs to correctly interpret that FORM.
  829.  
  830. Group CAT
  831.  
  832. A CAT is just an untyped group of data objects.
  833.  
  834. Structurally,  a  CAT  is  a chunk with  chunk  ID  "CAT  " containing a
  835. "contents  type"  ID followed by the  nested objects. The ckSize of each
  836. contained chunk is essentially a relative pointer to the next one.
  837.  
  838. CAT     ::= "CAT " #{ ContentsType (FORM | LIST | CAT)* }
  839. ContentsType    ::= ID  -- a hint or an "abstract data type" ID
  840.  
  841. In  reading  a  CAT, like any  other  chunk,  programs must respect it's
  842. ckSize  as a virtual end-of-file for  reading the nested objects even if
  843. they're malformed or truncated.
  844.  
  845. The  "contents  type" following the CAT's  ckSize indicates what kind of
  846. FORMs  are inside. So a CAT of ILBMs would store "ILBM" there. It's just
  847. a  hint.  It may be used to store  an  "abstract data type". A CAT could
  848. just  have blank contents ID ("JJJJ") if  it contains more than one kind
  849. of FORM.
  850.  
  851. CAT defines only the format of the group. The group's meaning is open to
  852. interpretation.  This is like a list in  LISP: the structure of cells is
  853. predefined  but the meaning of the contents as, say, an association list
  854. depends  on  use.  If  you need a  group  with  an  enforced meaning (an
  855. "abstract   data  type"  or   Smalltalk  "subclass"),  some  consistency
  856. constraints,  or  additional data chunks,  use  a composite FORM instead
  857. (Cf. Composite FORMs).
  858.  
  859. Since  a  CAT  just means a  concatenation  of  objects, CATs are rarely
  860. nested. Programs should really merge CATs rather than nest them.
  861.  
  862. Group LIST
  863.  
  864. A  LIST defines a group very much like CAT but it also gives a scope for
  865. PROPs  (see below). And unlike CATs,  LISTs should not be merged without
  866. understanding their contents.
  867.  
  868. Structurally,  a LIST is a chunk with ckID "LIST" containing a "contents
  869. type"  ID,  optional shared properties,  and the nested contents (FORMs,
  870. LISTs, and CATs), in that order. The ckSize of each contained chunk is a
  871. relative pointer to the next one. A LIST is not an arbitrary linked list
  872. the cells are simply concatenated.
  873.  
  874. LIST ::= "LIST" #{ ContentsType PROP* (FORM | LIST | CAT)* }
  875. ContentsType    ::= ID
  876.  
  877. Group PROP
  878.  
  879. PROP  chunks  may  appear in LISTs (not  in  FORMs or CATs). They supply
  880. shared  properties  for the FORMs in  that LIST. This ability to elevate
  881. some  property  settings to shared status for  a list of forms is useful
  882. for both indirection and compaction. E.g. a list of images with the same
  883. size  and  colors  can  share one  "size"  property  and one "color map"
  884. property. Individual FORMs can override the shared settings.
  885.  
  886. The contents of a PROP is like a FORM with no data chunks:
  887.  
  888. PROP ::= "PROP" #{ FormType Property* }
  889.  
  890. It means, "Here are the shared properties for FORM type <<FormType>."
  891.  
  892. A  LIST may have at most one PROP of a FORM type, and all the PROPs must
  893. appear  before  any of the FORMs or  nested LISTs and CATs. You can have
  894. subsequences  of  FORMs sharing properties  by making each subsequence a
  895. LIST.
  896.  
  897. Scoping:  Think  of  property settings  as  variable  bindings in nested
  898. blocks of a programming language. Where in C you could write:
  899.  
  900. TEXT_FONT text_font = Courier;  /* program's global default     */
  901.  
  902. File(); {
  903.         TEXT_FONT text_font = TimesRoman;       /* shared setting       */
  904.  
  905.                 {
  906.                 TEXT_FONT text_font = Helvetica;  /* local setting      */
  907.                 Print("Hello ");/* uses font Helvetica  */
  908.                 }
  909.  
  910.                 {
  911.                 Print("there.");/* uses font TimesRoman */
  912.                 }
  913.         }
  914.  
  915. An IFF file could contain:
  916.  
  917. LIST {
  918.         PROP TEXT {
  919.                 FONT {TimesRoman}       /* shared setting       */
  920.                 }
  921.  
  922.         FORM TEXT {
  923.                 FONT {Helvetica}/* local setting*/
  924.                 CHRS {Hello }           /* uses font Helvetica  */
  925.                 }
  926.  
  927.         FORM TEXT {
  928.                 CHRS {there.}   /* uses font TimesRoman */
  929.                 }
  930.         }
  931.  
  932. The shared property assignments selectively override the reader's global
  933. defaults,  but  only for FORMs within  the  group. A FORM's own property
  934. assignments  selectively override the  global and group-supplied values.
  935. So  when reading an IFF file, keep property settings on a stack. They're
  936. designed to be small enough to hold in main memory.
  937.  
  938. Shared   properties   are  semantically   equivalent  to  copying  those
  939. properties  into  each of the nested  FORMs  right after their FORM type
  940. IDs.
  941.  
  942. Properties for LIST
  943.  
  944. Optional  "properties for LIST" store the  origin of the list's contents
  945. in  a PROP chunk for the fake  FORM type "LIST". They are the properties
  946. originating  program  "OPGM",  processor  family  "OCPU",  computer type
  947. "OCMP",  computer serial number or network address "OSN ", and user name
  948. "UNAM".   In  our  imperfect  world,  these  could  be  called  upon  to
  949. distinguish  between  unintended variations of a  data format or to work
  950. around  bugs  in particular  originating/receiving program pairs. Issue:
  951. Specify the format of these properties.
  952.  
  953. A  creation  date could also be stored  in a property but let's ask that
  954. file  creating, editing, and transporting  programs maintain the correct
  955. date  in the local file system. Programs that move files between machine
  956. types are expected to copy across the creation dates.
  957.  
  958.  
  959. 6. Standard File Structure
  960.  
  961. File Structure Overview
  962.  
  963. An IFF file is just a single chunk of type FORM, LIST, or CAT. Therefore
  964. an  IFF file can be recognized by  its first 4 bytes: "FORM", "LIST", or
  965. "CAT ". Any file contents after the chunk's end are to be ignored.
  966.  
  967. Since  an  IFF file can be a  group of objects, programs that read/write
  968. single   objects  can  communicate  to  an  extent  with  programs  that
  969. read/write  groups. You're encouraged to  write programs that handle all
  970. the  objects  in  a LIST or CAT.  A  graphics editor, for example, could
  971. process  a  list of pictures as a  multiple page document, one page at a
  972. time.
  973.  
  974. Programs  should enforce IFF's syntactic  rules when reading and writing
  975. files.  This  ensures  robust  data  transfer.  The  public  domain  IFF
  976. reader/writer  subroutine  package does this  for you. A utility program
  977. "IFFCheck"  is  available  that  scans an  IFF  file  and  checks it for
  978. conformance to IFF's syntactic rules. IFFCheck also prints an outline of
  979. the  chunks  in the file, showing the  ckID  and ckSize of each. This is
  980. quite  handy  when  building  IFF  programs.  Example  programs are also
  981. available to show details of reading and writing IFF files.
  982.  
  983. A  merge program "IFFJoin" will be  available that logically appends IFF
  984. files  into  a single CAT group. It  "unwraps" each input file that is a
  985. CAT so that the combined file isn't nested CATs.
  986.  
  987. If  we need to revise the IFF  standard, the three anchoring IDs will be
  988. used  as "version numbers". That's why IDs "FOR1" through "FOR9", "LIS1"
  989. through "LIS9", and "CAT1" through "CAT9" are reserved.
  990.  
  991. IFF  formats are designed for  reasonable performance with floppy disks.
  992. We  achieve  considerable  simplicity  in  the  formats  and programs by
  993. relying  on the host file system rather than defining universal grouping
  994. structures  like directories for LIST contents. On huge storage systems,
  995. IFF  files could be leaf nodes in  a file structure like a B-tree. Let's
  996. hope the host file system implements that for us!
  997.  
  998. Thre  are two kinds of IFF files:  single purpose files and scrap files.
  999. They  differ  in the interpretation of  multiple data objects and in the
  1000. file's external type.
  1001.  
  1002. Single Purpose Files
  1003.  
  1004. A  single  purpose  IFF  file is  for  normal  "document"  and "archive"
  1005. storage.  This  is  in  contrast  with  "scrap  files"  (see  below) and
  1006. temporary backing storage (non-interchange files).
  1007.  
  1008. The  external  file type (or filename  extension,  depending on the host
  1009. file system) indicates the file's contents. It's generally the FORM type
  1010. of the data contained, hence the restrictions on FORM type IDs.
  1011.  
  1012. Programmers  and  users may pick an  "intended use" type as the filename
  1013. extension to make it easy to filter for the relevant files in a filename
  1014. requestor.  This is actually a "subclass" or "subtype" that conveniently
  1015. separates files of the same FORM type that have different uses. Programs
  1016. cannot  demand  conformity  to  its  expected  subtypes  without  overly
  1017. restricting  data interchange since they  cannot know about the subtypes
  1018. to  be  used  by future programs that  users  will want to exchange data
  1019. with.
  1020.  
  1021. Issue:  How  to generate 3-letter  MS-DOS  extensions from 4-letter FORM
  1022. type IDs?
  1023.  
  1024. Most  single  purpose files will be  a  single FORM (perhaps a composite
  1025. FORM   like  a  musical  score  containing  nested  FORMs  like  musical
  1026. instrument  descriptions). If it's a LIST or a CAT, programs should skip
  1027. over  unrecognized  objects  to read the  recognized  ones  or the first
  1028. recognized  one. Then a program that can  read a single purpose file can
  1029. read something out of a "scrap file", too.
  1030.  
  1031. Scrap Files
  1032.  
  1033. A  "scrap file" is for maximum interconnectivity in getting data between
  1034. programs;  the  core of a clipboard  function. Scrap files may have type
  1035. "IFF " or filename extension ".IFF".
  1036.  
  1037. A  scrap file is typically a CAT containing alternate representations of
  1038. the  same  basic  information. Include as  many  alternatives as you can
  1039. readily   generate.   This  redundancy   improves  interconnectivity  in
  1040. situations where we can't make all programs read and write super-general
  1041. formats. [Inside Macintosh chapter "Scrap Manager".] E.g. a graphically-
  1042. annotated musical score might be supplemented by a stripped down 4-voice
  1043. melody and by a text (the lyrics).
  1044.  
  1045. The  originating  program should write  the alternate representations in
  1046. order of "preference": most preferred (most comprehensive) type to least
  1047. preferred  (least comprehensive) type. A receiving program should either
  1048. use  the first appearing type that it  understands or search for its own
  1049. "preferred" type.
  1050.  
  1051. A scrap file should have at most one alternative of any type. (A LIST of
  1052. same  type objects is ok as one of the alternatives.) But don't count on
  1053. this  when reading; ignore extra sections of a type. Then a program that
  1054. reads scrap files can read something out of single purpose files.
  1055.  
  1056. Rules for Reader Programs
  1057.  
  1058. Here are some notes on building programs that read IFF files. If you use
  1059. the standard IFF reader module "IFFR.C", many of these rules and details
  1060. will  be automatically handled. (See  "Support Software" in Appendix A.)
  1061. We  recommend that you start from  the example program "ShowILBM.C". You
  1062. should  also  read up on recursive  descent  parsers. [See, for example,
  1063. Compiler Construction, An Advanced Course.]
  1064.  
  1065. %       The standard is very flexible so many programs can exchange
  1066. data. This implies a program has to scan the file and react to what's
  1067. actually there in whatever order it appears. An IFF reader program
  1068. is a parser.
  1069.  
  1070. %       For interchange to really work, programs must be willing to
  1071. do some conversion during read-in. If the data isn't exactly what
  1072. you expect, say, the raster is smaller than those created by your
  1073. program, then adjust it. Similarly, your program could crop a large
  1074. picture, add or drop bitplanes, and create/discard a mask plane. The
  1075. program should give up gracefully on data that it can't convert.
  1076.  
  1077. %       If it doesn't start with "FORM", "LIST", or "CAT ", it's not
  1078. an IFF-85 file.
  1079.  
  1080. %       For any chunk you encounter, you must recognize its type ID
  1081. to understand its contents.
  1082.  
  1083. %       For any FORM chunk you encounter, you must recognize its FORM
  1084. type ID to understand the contained "local chunks". Even if you don't
  1085. recognize the FORM type, you can still scan it for nested FORMs, LISTs,
  1086. and CATs of interest.
  1087.  
  1088. %       Don't forget to skip the pad byte after every odd-length chunk.
  1089.  
  1090. %       Chunk types LIST, FORM, PROP, and CAT are generic groups. They
  1091. always contain a subtype ID followed by chunks.
  1092.  
  1093. %       Readers ought to handle a CAT of FORMs in a file. You may treat
  1094. the FORMs like document pages to sequence through or just use the
  1095. first FORM.
  1096.  
  1097. %       Simpler IFF readers completely skip LISTs. "Fully IFF-conforming"
  1098. readers are those that handle LISTs, even if just to read the first
  1099. FORM from a file. If you do look into a LIST, you must process shared
  1100. properties (in PROP chunks) properly. The idea is to get the correct
  1101. data or none at all.
  1102.  
  1103. %       The nicest readers are willing to look into unrecognized FORMs
  1104. for nested FORM types that they do recognize. For example, a musical
  1105. score may contain nested instrument descriptions and an animation
  1106. file may contain still pictures.
  1107.  
  1108. Note to programmers: Processing PROP chunks is not simple! You'll
  1109. need some background in interpreters with stack frames. If this is
  1110. foreign to you, build programs that read/write only one FORM per file.
  1111. For the more intrepid programmers, the next paragraph summarizes how
  1112. to process LISTs and PROPs. See the general IFF reader module "IFFR.C"
  1113. and the example program "ShowILBM.C" for details.
  1114.  
  1115. Allocate  a  stack  frame  for every  LIST  and  FORM  you encounter and
  1116. initialize  it by copying the stack frame of the parent LIST or FORM. At
  1117. the  top level, you'll need a  stack frame initialized to your program's
  1118. global  defaults. While reading each LIST or FORM, store all encountered
  1119. properties  into the current stack frame.  In the example ShowILBM, each
  1120. stack  frame  has a place for a  bitmap  header property ILBM.BMHD and a
  1121. color  map  property ILBM.CMAP. When you  finally get to the ILBM's BODY
  1122. chunk, use the property settings accumulated in the current stack frame.
  1123.  
  1124. An  alternate  implementation  would  just  remember  PROPs encountered,
  1125. forgetting  each  on  reaching  the end of  its  scope  (the  end of the
  1126. containing  LIST).  When a FORM XXXX  is encountered, scan the chunks in
  1127. all  remembered  PROPs  XXXX, in order,  as  if they appeared before the
  1128. chunks  actually in the FORM XXXX. This  gets trickier if you read FORMs
  1129. inside of FORMs.
  1130.  
  1131. Rules for Writer Programs
  1132.  
  1133. Here  are some notes on building programs that write IFF files, which is
  1134. much easier than reading them. If you use the standard IFF writer module
  1135. "IFFW.C" (see "Support Software" in Appendix A), many of these rules and
  1136. details   will  automatically  be  enforced.  See  the  example  program
  1137. "Raw2ILBM.C".
  1138.  
  1139. %       An IFF file is a single FORM, LIST, or CAT chunk.
  1140.  
  1141. %       Any IFF-85 file must start with the 4 characters "FORM", "LIST",
  1142. or "CAT ", followed by a LONG ckSize. There should be no data after
  1143. the chunk end.
  1144.  
  1145. %       Chunk types LIST, FORM, PROP, and CAT are generic. They always
  1146. contain a subtype ID followed by chunks. These three IDs are universally
  1147. reserved, as are "LIS1" through "LIS9", "FOR1" through "FOR9", "CAT1"
  1148. through "CAT9", and "    ".
  1149.  
  1150. %       Don't forget to write a 0 pad byte after each odd-length chunk.
  1151.  
  1152. %       Four techniques for writing an IFF group: (1) build the data
  1153. in a file mapped into virtual memory, (2) build the data in memory
  1154. blocks and use block I/O, (3) stream write the data piecemeal and
  1155. (don't forget!) random access back to set the group length count,
  1156. and (4) make a preliminary pass to compute the length count then stream
  1157. write the data.
  1158.  
  1159. %       Do not try to edit a file that you don't know how to create.
  1160. Programs may look into a file and copy out nested FORMs of types that
  1161. they recognize, but don't edit and replace the nested FORMs and don't
  1162. add or remove them. That could make the containing structure inconsistent.
  1163. You may write a new file containing items you copied (or copied and
  1164. modified) from another IFF file, but don't copy structural parts you
  1165. don't understand.
  1166.  
  1167. %       You must adhere to the syntax descriptions in Appendex A. E.g.
  1168. PROPs may only appear inside LISTs.
  1169.  
  1170.  
  1171. Appendix A. Reference
  1172.  
  1173. Type Definitions
  1174.  
  1175. The  following C typedefs describe standard IFF structures. Declarations
  1176. to  use  in practice will vary with  the  CPU and compiler. For example,
  1177. 68000  Lattice C produces efficient comparison code if we define ID as a
  1178. "LONG". A macro "MakeID" builds these IDs at compile time.
  1179.  
  1180. /* Standard IFF types, expressed in 68000 Lattice C.    */
  1181.  
  1182. typedef unsigned char UBYTE;    /*  8 bits unsigned     */
  1183. typedef short WORD;     /* 16 bits signed       */
  1184. typedef unsigned short UWORD;   /* 16 bits unsigned     */
  1185. typedef long LONG;      /* 32 bits signed       */
  1186.  
  1187. typedef char ID[4];     /* 4 chars in ' ' through '~'   */
  1188.  
  1189. typedef struct {
  1190.         ID      ckID;
  1191.         LONG    ckSize; /* sizeof(ckData)       */
  1192.         UBYTE   ckData[/* ckSize */];
  1193.         } Chunk;
  1194.  
  1195. /* ID typedef and builder for 68000 Lattice C. */
  1196. typedef LONG ID;        /* 4 chars in ' ' through '~'   */
  1197. #define MakeID(a,b,c,d) ( (a)<<<<24 | (b)<<<<16 | (c)<<<<8 | (d) )
  1198.  
  1199. /* Globally reserved IDs. */
  1200. #define ID_FORM   MakeID('F','O','R','M')
  1201. #define ID_LIST   MakeID('L','I','S','T')
  1202. #define ID_PROP   MakeID('P','R','O','P')
  1203. #define ID_CAT    MakeID('C','A','T',' ')
  1204. #define ID_FILLER MakeID(' ',' ',' ',' ')
  1205.  
  1206. Syntax Definitions
  1207.  
  1208. Here's a collection of the syntax definitions in this document.
  1209.  
  1210. Chunk   ::= ID #{ UBYTE* } [0]
  1211.  
  1212. Property::= Chunk
  1213.  
  1214. FORM    ::= "FORM" #{ FormType (LocalChunk | FORM | LIST | CAT)*
  1215. }
  1216. FormType::= ID
  1217. LocalChunk      ::= Property | Chunk
  1218.  
  1219. CAT     ::= "CAT " #{ ContentsType (FORM | LIST | CAT)* }
  1220. ContentsType    ::= ID  -- a hint or an "abstract data type" ID
  1221.  
  1222. LIST    ::= "LIST" #{ ContentsType PROP* (FORM | LIST | CAT)* }
  1223. PROP    ::= "PROP" #{ FormType Property* }
  1224.  
  1225. In this extended regular expression notation, the token "#" represents a
  1226. ckSize  LONG  count of the following  {braced} data bytes. Literal items
  1227. are  shown  in "quotes", [square bracketed  items] are optional, and "*"
  1228. means  0  or  more instances. A  sometimes-needed  pad  byte is shown as
  1229. "[0]".
  1230.  
  1231. Defined Chunk IDs
  1232.  
  1233. This  is a table of currently defined chunk IDs. We may also borrow some
  1234. Macintosh IDs and data formats.
  1235.  
  1236. Group chunk IDs
  1237.         FORM, LIST, PROP, CAT.
  1238. Future revision group chunk IDs
  1239.         FOR1 I FOR9, LIS1 I LIS9, CAT1 I CAT9.
  1240. FORM type IDs
  1241.         (The above group chunk IDs may not be used for FORM type IDs.)
  1242.         (Lower case letters and punctuation marks are forbidden in FORM
  1243. type IDs.)
  1244.         8SVX 8-bit sampled sound voice, ANBM animated bitmap, FNTR raster
  1245. font, FNTV vector font, FTXT formatted text, GSCR general-use musical
  1246. score, ILBM interleaved raster bitmap image, PDEF Deluxe Print page
  1247. definition, PICS Macintosh picture, PLBM (obsolete), USCR Uhuru Sound
  1248. Software musical score, UVOX Uhuru Sound Software Macintosh voice,
  1249. SMUS simple musical score, VDEO Deluxe Video Construction Set video.
  1250. Data chunk IDs
  1251.         "JJJJ", TEXT, PICT.
  1252. PROP LIST property IDs
  1253.         OPGM, OCPU, OCMP, OSN, UNAM.
  1254.  
  1255.  
  1256.  
  1257. Support Software
  1258.  
  1259. These  public domain C source programs are available for use in building
  1260. IFF-compatible programs:
  1261.  
  1262. IFF.H, IFFR.C, IFFW.C
  1263.  
  1264.                 IFF reader and writer package.
  1265.                 These modules handle many of the details of reliably
  1266.                 reading and writing IFF files.
  1267.  
  1268. IFFCheck.C      This handy utility program scans an IFF file, checks
  1269.                 that the contents are well formed, and prints an outline
  1270.                 of the chunks.
  1271.  
  1272. PACKER.H, Packer.C, UnPacker.C
  1273.  
  1274.                 Run encoder and decoder used for ILBM files.
  1275.  
  1276. ILBM.H, ILBMR.C, ILBMW.C
  1277.  
  1278.                 Reader and writer support routines for raster image
  1279.                 FORM ILBM. ILBMR calls IFFR and UnPacker. ILBMW calls
  1280.                 IFFW and Packer.
  1281.  
  1282. ShowILBM.C
  1283.                 Example caller of IFFR and ILBMR modules. This
  1284.                 Commodore-Amiga program reads and displays a FORM ILBM.
  1285. Raw2ILBM.C
  1286.                 Example ILBM writer program. As a demonstration, it
  1287.                 reads a raw raster image file and writes the image
  1288.                 as a FORM ILBM file.
  1289. ILBM2Raw.C
  1290.                 Example ILBM reader program.  Reads a FORM ILBM file
  1291.                 and writes it into a raw raster image.
  1292.  
  1293. REMALLOC.H, Remalloc.c
  1294.  
  1295.                 Memory allocation routines used in these examples.
  1296.  
  1297. INTUALL.H       generic "include almost everything" include-file
  1298.                 with the sequence of includes correctly specified.
  1299.  
  1300. READPICT.H, ReadPict.c
  1301.  
  1302.                 given an ILBM file, read it into a bitmap and
  1303.                 a color map
  1304.  
  1305. PUTPICT.H, PutPict.c
  1306.  
  1307.                 given a bitmap and a color map, save it as
  1308.                 an ILBM file.
  1309.  
  1310. GIO.H, Gio.c    generic I/O speedup package.  Attempts to speed
  1311.                 disk I/O by buffering writes and reads.
  1312.  
  1313. giocall.c       sample call to gio.
  1314.  
  1315. ilbmdump.c      reads in ILBM file, prints out ascii representation
  1316.                 for including in C files.
  1317.  
  1318. bmprintc.c      prints out a C-language representation of data for
  1319.                 a bitmap.
  1320.  
  1321.  
  1322.  
  1323. Example Diagrams
  1324.  
  1325. Here's  a box diagram for an example IFF file, a raster image FORM ILBM.
  1326. This  FORM  contains  a bitmap header  property  chunk BMHD, a color map
  1327. property  chunk  CMAP,  and a raster  data  chunk  BODY. This particular
  1328. raster  is  320 x 200 pixels x  3 bit planes uncompressed. The "0" after
  1329. the CMAP chunk represents a zero pad byte; included since the CMAP ch